[clang-doc] separate comments into categories #149564
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Jul 18, 2025
Member
Author
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
Member
|
@llvm/pr-subscribers-clang-tools-extra Author: Erick Velez (evelez7) ChangesComment categories will allow better comment organization in HTML. Full diff: https://github.com/llvm/llvm-project/pull/149564.diff 3 Files Affected:
diff --git a/clang-tools-extra/clang-doc/JSONGenerator.cpp b/clang-tools-extra/clang-doc/JSONGenerator.cpp
index 908e23d24d079..5c2cb1c75cfee 100644
--- a/clang-tools-extra/clang-doc/JSONGenerator.cpp
+++ b/clang-tools-extra/clang-doc/JSONGenerator.cpp
@@ -83,7 +83,20 @@ serializeLocation(const Location &Loc,
return LocationObj;
}
-static json::Value serializeComment(const CommentInfo &I) {
+static void insertComment(Object &Description, json::Value &Comment, std::string Key) {
+ auto *CommentArray = Description.getArray(Key);
+ if (!CommentArray) {
+ auto CommentsArray= json::Array();
+ CommentsArray.push_back(Comment);
+ Description[Key] = std::move(CommentsArray);
+ Description["Has" + Key] = true;
+ } else {
+ CommentArray->push_back(Comment);
+ Description[Key] = std::move(*CommentArray);
+ }
+}
+
+static Object serializeComment(const CommentInfo &I, Object &Description) {
// taken from PR #142273
Object Obj = Object();
@@ -94,7 +107,7 @@ static json::Value serializeComment(const CommentInfo &I) {
auto &CARef = *ChildArr.getAsArray();
CARef.reserve(I.Children.size());
for (const auto &C : I.Children)
- CARef.emplace_back(serializeComment(*C));
+ CARef.emplace_back(serializeComment(*C, Description));
switch (I.Kind) {
case CommentKind::CK_TextComment: {
@@ -106,6 +119,8 @@ static json::Value serializeComment(const CommentInfo &I) {
Child.insert({"Command", I.Name});
Child.insert({"Children", ChildArr});
Obj.insert({commentKindToString(I.Kind), ChildVal});
+ if (I.Name == "brief")
+ insertComment(Description, ChildVal, "BriefComments");
return Obj;
}
@@ -137,7 +152,10 @@ static json::Value serializeComment(const CommentInfo &I) {
if (!I.CloseName.empty())
Child.insert({"CloseName", I.CloseName});
Child.insert({"Children", ChildArr});
- Obj.insert({commentKindToString(I.Kind), ChildVal});
+ if (I.CloseName == "endcode")
+ insertComment(Description, ChildVal, "CodeComments");
+ else if (I.CloseName == "endverbatim")
+ insertComment(Description, ChildVal, "VerbatimComments");
return Obj;
}
@@ -210,12 +228,17 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
}
if (!I.Description.empty()) {
- json::Value DescArray = json::Array();
- auto &DescArrayRef = *DescArray.getAsArray();
- DescArrayRef.reserve(I.Description.size());
- for (const auto &Comment : I.Description)
- DescArrayRef.push_back(serializeComment(Comment));
- Obj["Description"] = DescArray;
+ Object Description = Object();
+ // Skip straight to the FullComment's children
+ auto &Comments = I.Description.at(0).Children;
+ for (const auto &CommentInfo: Comments)
+ {
+ json::Value Comment = serializeComment(*CommentInfo, Description);
+ // Paragraph comments might not be children
+ if (auto *ParagraphComment = Comment.getAsObject()->get("ParagraphComment"))
+ insertComment(Description, *ParagraphComment, "ParagraphComments");
+ }
+ Obj["Description"] = std::move(Description);
}
// Namespaces aren't SymbolInfos, so they dont have a DefLoc
diff --git a/clang-tools-extra/test/clang-doc/json/class.cpp b/clang-tools-extra/test/clang-doc/json/class.cpp
index a36358982b019..e8fafca28a956 100644
--- a/clang-tools-extra/test/clang-doc/json/class.cpp
+++ b/clang-tools-extra/test/clang-doc/json/class.cpp
@@ -33,33 +33,30 @@ struct MyClass {
};
// CHECK: {
-// CHECK-NEXT: "Description": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "FullComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "ParagraphComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "TextComment": " This is a nice class."
-// CHECK-NEXT: },
-// CHECK-NEXT: {
-// CHECK-NEXT: "TextComment": " It has some nice methods and fields."
-// CHECK-NEXT: },
-// CHECK-NEXT: {
-// CHECK-NEXT: "TextComment": ""
-// CHECK-NEXT: }
-// CHECK-NEXT: ]
-// CHECK: {
-// CHECK-NEXT: "BlockCommandComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "ParagraphComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "TextComment": " This is a brief description."
-// CHECK-NEXT: }
-// CHECK: "Command": "brief"
+// CHECK-NEXT: "Description": {
+// CHECK-NEXT: "BriefComments": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "Children": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "ParagraphComment": {
+// CHECK-NEXT: "Children": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "TextComment": " This is a brief description."
+// CHECK: "Command": "brief"
+// CHECK: "HasBriefComments": true,
+// CHECK-NEXT: "HasParagraphComments": true,
+// CHECK-NEXT: "ParagraphComments": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "Children": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "TextComment": " This is a nice class."
+// CHECK-NEXT: },
+// CHECK-NEXT: {
+// CHECK-NEXT: "TextComment": " It has some nice methods and fields."
+// CHECK-NEXT: },
+// CHECK-NEXT: {
+// CHECK-NEXT: "TextComment": ""
+// CHECK-NEXT: }
// CHECK: "DocumentationFileName": "_ZTV7MyClass",
// CHECK: "Enums": [
// CHECK-NEXT: {
diff --git a/clang-tools-extra/test/clang-doc/json/concept.cpp b/clang-tools-extra/test/clang-doc/json/concept.cpp
index 766415bbbeecd..2874caf28f8f5 100644
--- a/clang-tools-extra/test/clang-doc/json/concept.cpp
+++ b/clang-tools-extra/test/clang-doc/json/concept.cpp
@@ -13,16 +13,13 @@ concept Incrementable = requires(T x) {
// CHECK-NEXT: "Concepts": [
// CHECK-NEXT: {
// CHECK-NEXT: "ConstraintExpression": "requires (T x) { ++x; x++; }",
-// CHECK-NEXT: "Description": [
+// CHECK-NEXT: "Description": {
+// CHECK-NEXT: "HasParagraphComments": true,
+// CHECK-NEXT: "ParagraphComments": [
// CHECK-NEXT: {
-// CHECK-NEXT: "FullComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "ParagraphComment": {
-// CHECK-NEXT: "Children": [
-// CHECK-NEXT: {
-// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing."
-// CHECK: ],
+// CHECK-NEXT: "Children": [
+// CHECK-NEXT: {
+// CHECK-NEXT: "TextComment": " Requires that T suports post and pre-incrementing."
// CHECK: "End": true,
// CHECK-NEXT: "InfoType": "concept",
// CHECK-NEXT: "IsType": true,
|
|
✅ With the latest revision this PR passed the C/C++ code formatter. |
Comment categories will allow better comment organization in HTML. Before, comments would just be serialized in whatever order they were written, so groups like params or notes wouldn't be in the same sections.
evelez7
force-pushed
the
users/evelez7/clang-doc-revamp-comments
branch
from
959b078 to
0e6eaa3
Compare
ilovepi
reviewed
Jul 18, 2025
Contributor
ilovepi
left a comment
ilovepi
left a comment
There was a problem hiding this comment.
This seems mostly fine. I'll probably LGTM once I go through the whole stack.
Comment on lines
+237
to
+240
| // Paragraph comments might not be children | ||
| if (auto *ParagraphComment = | ||
| Comment.getAsObject()->get("ParagraphComment")) | ||
| insertComment(Description, *ParagraphComment, "ParagraphComments"); |
Contributor
There was a problem hiding this comment.
The comment here implies to me that we may be missing paragraph comments. Am I understanding that correctly?
Member
Author
There was a problem hiding this comment.
Not really, because all paragraph comments were previously handled.
This is meant to signal that there are top level ParagraphComments that can be returned from serializeComment that need to be manually inserted into Description with this modified scheme. They can't be added like brief comments now are because we can't be sure if the ParagraphComment is nested (the text of a brief command is a paragraph comment). So, if the returned comment is a ParagraphComment, then it must be a top-level, standalone comment without a command.
Maybe this comment could use a revision. I just wanted to clarify why the ParagraphComment is handled specially here.
Contributor
There was a problem hiding this comment.
yeah, rewording would be helpful. thanks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Comment categories will allow better comment organization in HTML.
Before, comments would just be serialized in whatever order they were
written, so groups like params or notes wouldn't be in the same
sections.